home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 January: Mac OS SDK / Dev.CD Jan 98 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / PInterfaces / NetSprocket.p < prev    next >
Encoding:
Text File  |  1997-08-12  |  13.7 KB  |  369 lines  |  [TEXT/MPS ]
  1. {
  2.      File:        NetSprocket.p
  3.  
  4.      Contains:    Games Sprockets: NetSprocket interfaces
  5.  
  6.      Version:    Technology:    NetSprocket 1.0.2
  7.                  Release:    Universal Interfaces 3.0.1
  8.  
  9.      Copyright:    © 1996-1997 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. }
  18. {$IFC UNDEFINED UsingIncludes}
  19. {$SETC UsingIncludes := 0}
  20. {$ENDC}
  21.  
  22. {$IFC NOT UsingIncludes}
  23.  UNIT NetSprocket;
  24.  INTERFACE
  25. {$ENDC}
  26.  
  27. {$IFC UNDEFINED __NETSPROCKET__}
  28. {$SETC __NETSPROCKET__ := 1}
  29.  
  30. {$I+}
  31. {$SETC NetSprocketIncludes := UsingIncludes}
  32. {$SETC UsingIncludes := 1}
  33.  
  34. {$IFC UNDEFINED __TYPES__}
  35. {$I Types.p}
  36. {$ENDC}
  37. {$IFC UNDEFINED __EVENTS__}
  38. {$I Events.p}
  39. {$ENDC}
  40.  
  41. {$IFC UNDEFINED __OPENTRANSPORT__}
  42. {$I OpenTransport.p}
  43. {$ENDC}
  44. {$IFC UNDEFINED __OPENTPTINTERNET__}
  45. {$I OpenTptInternet.p}
  46. {$ENDC}
  47.  
  48.  
  49. {$PUSH}
  50. {$ALIGN POWER}
  51. {$LibExport+}
  52.  
  53.  
  54. CONST
  55.     kNSpMaxPlayerNameLen        = 31;
  56.     kNSpMaxGroupNameLen            = 31;
  57.     kNSpMaxPasswordLen            = 31;
  58.     kNSpMaxGameNameLen            = 31;
  59.     kNSpMaxDefinitionStringLen    = 255;
  60.  
  61.  
  62. { NetSprocket basic types }
  63.  
  64. TYPE
  65.     NSpGameReference = ^LONGINT;
  66.     NSpProtocolReference = ^LONGINT;
  67.     NSpProtocolListReference = ^LONGINT;
  68.     NSpAddressReference = ^LONGINT;
  69.     NSpEventCode                        = SInt32;
  70.     NSpGameID                            = SInt32;
  71.     NSpPlayerID                            = SInt32;
  72.     NSpGroupID                            = NSpPlayerID;
  73.     NSpPlayerType                        = UInt32;
  74.     NSpFlags                            = SInt32;
  75. { Individual player info }
  76.     NSpPlayerInfoPtr = ^NSpPlayerInfo;
  77.     NSpPlayerInfo = RECORD
  78.         id:                        NSpPlayerID;
  79.         playerType:                NSpPlayerType;                            {  was type }
  80.         name:                    Str31;
  81.         groupCount:                UInt32;
  82.         groups:                    ARRAY [0..0] OF NSpGroupID;
  83.     END;
  84.  
  85. { list of all players }
  86.     NSpPlayerEnumerationPtr = ^NSpPlayerEnumeration;
  87.     NSpPlayerEnumeration = RECORD
  88.         count:                    UInt32;
  89.         playerInfo:                ARRAY [0..0] OF NSpPlayerInfoPtr;
  90.     END;
  91.  
  92. { Individual group info }
  93.     NSpGroupInfoPtr = ^NSpGroupInfo;
  94.     NSpGroupInfo = RECORD
  95.         id:                        NSpGroupID;
  96.         playerCount:            UInt32;
  97.         players:                ARRAY [0..0] OF NSpPlayerID;
  98.     END;
  99.  
  100. { List of all groups }
  101.     NSpGroupEnumerationPtr = ^NSpGroupEnumeration;
  102.     NSpGroupEnumeration = RECORD
  103.         count:                    UInt32;
  104.         groups:                    ARRAY [0..0] OF NSpGroupInfoPtr;
  105.     END;
  106.  
  107. { Topology types }
  108.     NSpTopology                            = UInt32;
  109.  
  110. CONST
  111.     kNSpClientServer            = $00000001;
  112.  
  113. { Game information }
  114.  
  115. TYPE
  116.     NSpGameInfoPtr = ^NSpGameInfo;
  117.     NSpGameInfo = RECORD
  118.         maxPlayers:                UInt32;
  119.         currentPlayers:            UInt32;
  120.         currentGroups:            UInt32;
  121.         topology:                NSpTopology;
  122.         reserved:                UInt32;
  123.         name:                    Str31;
  124.         password:                Str31;
  125.     END;
  126.  
  127. { Structure used for sending and receiving network messages }
  128.     NSpMessageHeaderPtr = ^NSpMessageHeader;
  129.     NSpMessageHeader = RECORD
  130.         version:                UInt32;                                    {  Used by NetSprocket.  Don't touch this  }
  131.         what:                    SInt32;                                    {  The kind of message (e.g. player joined)  }
  132.         from:                    NSpPlayerID;                            {  ID of the sender  }
  133.         toID:                    NSpPlayerID;                            {  (player or group) id of the intended recipient (was "to)  }
  134.         id:                        UInt32;                                    {  Unique ID for this message & (from) player  }
  135.         when:                    UInt32;                                    {  Timestamp for the message  }
  136.         messageLen:                UInt32;                                    {  Bytes of data in the entire message (including the header)  }
  137.     END;
  138.  
  139. { NetSprocket-defined message structures }
  140.     NSpErrorMessagePtr = ^NSpErrorMessage;
  141.     NSpErrorMessage = RECORD
  142.         header:                    NSpMessageHeader;
  143.         error:                    OSStatus;
  144.     END;
  145.  
  146.     NSpJoinRequestMessagePtr = ^NSpJoinRequestMessage;
  147.     NSpJoinRequestMessage = RECORD
  148.         header:                    NSpMessageHeader;
  149.         name:                    Str31;
  150.         password:                Str31;
  151.         theType:                UInt32;
  152.         customDataLen:            UInt32;
  153.         customData:                SInt8;
  154.     END;
  155.  
  156.     NSpJoinApprovedMessagePtr = ^NSpJoinApprovedMessage;
  157.     NSpJoinApprovedMessage = RECORD
  158.         header:                    NSpMessageHeader;
  159.     END;
  160.  
  161.     NSpJoinDeniedMessagePtr = ^NSpJoinDeniedMessage;
  162.     NSpJoinDeniedMessage = RECORD
  163.         header:                    NSpMessageHeader;
  164.         reason:                    Str255;
  165.     END;
  166.  
  167.     NSpPlayerJoinedMessagePtr = ^NSpPlayerJoinedMessage;
  168.     NSpPlayerJoinedMessage = RECORD
  169.         header:                    NSpMessageHeader;
  170.         playerCount:            UInt32;
  171.         playerInfo:                NSpPlayerInfo;
  172.     END;
  173.  
  174.     NSpPlayerLeftMessagePtr = ^NSpPlayerLeftMessage;
  175.     NSpPlayerLeftMessage = RECORD
  176.         header:                    NSpMessageHeader;
  177.         playerCount:            UInt32;
  178.         playerID:                NSpPlayerID;
  179.     END;
  180.  
  181.     NSpHostChangedMessagePtr = ^NSpHostChangedMessage;
  182.     NSpHostChangedMessage = RECORD
  183.         header:                    NSpMessageHeader;
  184.         newHost:                NSpPlayerID;
  185.     END;
  186.  
  187.     NSpGameTerminatedMessagePtr = ^NSpGameTerminatedMessage;
  188.     NSpGameTerminatedMessage = RECORD
  189.         header:                    NSpMessageHeader;
  190.     END;
  191.  
  192. { Different kinds of messages.  These can NOT be bitwise ORed together }
  193.  
  194. CONST
  195.     kNSpSendFlag_Junk            = $00100000;                    {  will be sent (try once) when there is nothing else pending  }
  196.     kNSpSendFlag_Normal            = $00200000;                    {  will be sent immediately (try once)  }
  197.     kNSpSendFlag_Registered        = $00400000;                    {  will be sent immediately (guaranteed, in order)  }
  198.  
  199.  
  200. { Options for message delivery.  These can be bitwise ORed together with each other,
  201.         as well as with ONE of the above }
  202.     kNSpSendFlag_FailIfPipeFull    = $00000001;
  203.     kNSpSendFlag_SelfSend        = $00000002;
  204.     kNSpSendFlag_Blocking        = $00000004;
  205.  
  206.  
  207. { Options for Hosting Joining, and Deleting games }
  208.     kNSpGameFlag_DontAdvertise    = $00000001;
  209.     kNSpGameFlag_ForceTerminateGame = $00000002;
  210.  
  211. { Message "what" types }
  212. { Apple reserves all negative "what" values (anything with bit 32 set) }
  213.     kNSpSystemMessagePrefix        = $80000000;
  214.     kNSpError                    = $FFFFFFFF;
  215.     kNSpJoinRequest                = $80000001;
  216.     kNSpJoinApproved            = $80000002;
  217.     kNSpJoinDenied                = $80000003;
  218.     kNSpPlayerJoined            = $80000004;
  219.     kNSpPlayerLeft                = $80000005;
  220.     kNSpHostChanged                = $80000006;
  221.     kNSpGameTerminated            = $80000007;
  222.  
  223.  
  224. { Special TPlayerIDs  for sending messages }
  225.     kNSpAllPlayers                = $00000000;
  226.     kNSpHostOnly                = $FFFFFFFF;
  227.  
  228.  
  229. { NetSprocket Error Codes }
  230.     kNSpInitializationFailedErr    = -30360;
  231.     kNSpAlreadyInitializedErr    = -30361;
  232.     kNSpTopologyNotSupportedErr    = -30362;
  233.     kNSpPipeFullErr                = -30364;
  234.     kNSpHostFailedErr            = -30365;
  235.     kNSpProtocolNotAvailableErr    = -30366;
  236.     kNSpInvalidGameRefErr        = -30367;
  237.     kNSpInvalidParameterErr        = -30369;
  238.     kNSpOTNotPresentErr            = -30370;
  239.     kNSpOTVersionTooOldErr        = -30371;
  240.     kNSpMemAllocationErr        = -30373;
  241.     kNSpAlreadyAdvertisingErr    = -30374;
  242.     kNSpNotAdvertisingErr        = -30376;
  243.     kNSpInvalidAddressErr        = -30377;
  244.     kNSpFreeQExhaustedErr        = -30378;
  245.     kNSpRemovePlayerFailedErr    = -30379;
  246.     kNSpAddressInUseErr            = -30380;
  247.     kNSpFeatureNotImplementedErr = -30381;
  248.     kNSpNameRequiredErr            = -30382;
  249.     kNSpInvalidPlayerIDErr        = -30383;
  250.     kNSpInvalidGroupIDErr        = -30384;
  251.     kNSpNoPlayersErr            = -30385;
  252.     kNSpNoGroupsErr                = -30386;
  253.     kNSpNoHostVolunteersErr        = -30387;
  254.     kNSpCreateGroupFailedErr    = -30388;
  255.     kNSpAddPlayerFailedErr        = -30389;
  256.     kNSpInvalidDefinitionErr    = -30390;
  257.     kNSpInvalidProtocolRefErr    = -30391;
  258.     kNSpInvalidProtocolListErr    = -30392;
  259.     kNSpTimeoutErr                = -30393;
  260.     kNSpGameTerminatedErr        = -30394;
  261.     kNSpConnectFailedErr        = -30395;
  262.     kNSpSendFailedErr            = -30396;
  263.     kNSpJoinFailedErr            = -30399;
  264.  
  265.  
  266.  
  267.  
  268. {***********************  Initialization  ***********************}
  269. FUNCTION NSpInitialize(inStandardMessageSize: UInt32; inBufferSize: UInt32; inQElements: UInt32; inGameID: NSpGameID; inTimeout: UInt32): OSStatus; C;
  270.  
  271.  
  272.  
  273. {*************************  Protocols  *************************}
  274. { Programmatic protocol routines }
  275. FUNCTION NSpProtocol_New(inDefinitionString: ConstCStringPtr; VAR outReference: NSpProtocolReference): OSStatus; C;
  276. PROCEDURE NSpProtocol_Dispose(inProtocolRef: NSpProtocolReference); C;
  277. FUNCTION NSpProtocol_ExtractDefinitionString(inProtocolRef: NSpProtocolReference; outDefinitionString: CStringPtr): OSStatus; C;
  278.  
  279. { Protocol list routines }
  280. FUNCTION NSpProtocolList_New(inProtocolRef: NSpProtocolReference; VAR outList: NSpProtocolListReference): OSStatus; C;
  281. PROCEDURE NSpProtocolList_Dispose(inProtocolList: NSpProtocolListReference); C;
  282. FUNCTION NSpProtocolList_Append(inProtocolList: NSpProtocolListReference; inProtocolRef: NSpProtocolReference): OSStatus; C;
  283. FUNCTION NSpProtocolList_Remove(inProtocolList: NSpProtocolListReference; inProtocolRef: NSpProtocolReference): OSStatus; C;
  284. FUNCTION NSpProtocolList_RemoveIndexed(inProtocolList: NSpProtocolListReference; inIndex: UInt32): OSStatus; C;
  285. FUNCTION NSpProtocolList_GetCount(inProtocolList: NSpProtocolListReference): UInt32; C;
  286. FUNCTION NSpProtocolList_GetIndexedRef(inProtocolList: NSpProtocolListReference; inIndex: UInt32): NSpProtocolReference; C;
  287.  
  288. { Helpers }
  289. FUNCTION NSpProtocol_CreateAppleTalk(inNBPName: ConstStr31Param; inNBPType: ConstStr31Param; inMaxRTT: UInt32; inMinThruput: UInt32): NSpProtocolReference; C;
  290. FUNCTION NSpProtocol_CreateIP(inPort: InetPort; inMaxRTT: UInt32; inMinThruput: UInt32): NSpProtocolReference; C;
  291.  
  292. {**********************  Human Interface  ***********************}
  293.  
  294. TYPE
  295.     NSpEventProcPtr = ProcPtr;  { FUNCTION NSpEvent(VAR inEvent: EventRecord): BOOLEAN; }
  296.  
  297. FUNCTION NSpDoModalJoinDialog(inGameType: ConstStr31Param; inEntityListLabel: ConstStr255Param; VAR ioName: Str31; VAR ioPassword: Str31; inEventProcPtr: NSpEventProcPtr): NSpAddressReference; C;
  298. FUNCTION NSpDoModalHostDialog(ioProtocolList: NSpProtocolListReference; VAR ioGameName: Str31; VAR ioPlayerName: Str31; VAR ioPassword: Str31; inEventProcPtr: NSpEventProcPtr): BOOLEAN; C;
  299.  
  300. {********************  Hosting and Joining  *********************}
  301. FUNCTION NSpGame_Host(VAR outGame: NSpGameReference; inProtocolList: NSpProtocolListReference; inMaxPlayers: UInt32; inGameName: ConstStr31Param; inPassword: ConstStr31Param; inPlayerName: ConstStr31Param; inPlayerType: NSpPlayerType; inTopology: NSpTopology; inFlags: NSpFlags): OSStatus; C;
  302. FUNCTION NSpGame_Join(VAR outGame: NSpGameReference; inAddress: NSpAddressReference; inName: ConstStr31Param; inPassword: ConstStr31Param; inType: NSpPlayerType; inCustomData: UNIV Ptr; inCustomDataLen: UInt32; inFlags: NSpFlags): OSStatus; C;
  303. FUNCTION NSpGame_EnableAdvertising(inGame: NSpGameReference; inProtocol: NSpProtocolReference; inEnable: BOOLEAN): OSStatus; C;
  304. FUNCTION NSpGame_Dispose(inGame: NSpGameReference; inFlags: NSpFlags): OSStatus; C;
  305. FUNCTION NSpGame_GetInfo(inGame: NSpGameReference; VAR ioInfo: NSpGameInfo): OSStatus; C;
  306. {*************************  Messaging  *************************}
  307. FUNCTION NSpMessage_Send(inGame: NSpGameReference; VAR inMessage: NSpMessageHeader; inFlags: NSpFlags): OSStatus; C;
  308. FUNCTION NSpMessage_Get(inGame: NSpGameReference): NSpMessageHeaderPtr; C;
  309. PROCEDURE NSpMessage_Release(inGame: NSpGameReference; VAR inMessage: NSpMessageHeader); C;
  310. { Helpers }
  311. FUNCTION NSpMessage_SendTo(inGame: NSpGameReference; inTo: NSpPlayerID; inWhat: SInt32; inData: UNIV Ptr; inDataLen: UInt32; inFlags: NSpFlags): OSStatus; C;
  312.  
  313. {********************  Player Information  *********************}
  314. FUNCTION NSpPlayer_GetMyID(inGame: NSpGameReference): NSpPlayerID; C;
  315. FUNCTION NSpPlayer_GetInfo(inGame: NSpGameReference; inPlayerID: NSpPlayerID; VAR outInfo: NSpPlayerInfoPtr): OSStatus; C;
  316. PROCEDURE NSpPlayer_ReleaseInfo(inGame: NSpGameReference; inInfo: NSpPlayerInfoPtr); C;
  317. FUNCTION NSpPlayer_GetEnumeration(inGame: NSpGameReference; VAR outPlayers: NSpPlayerEnumerationPtr): OSStatus; C;
  318. PROCEDURE NSpPlayer_ReleaseEnumeration(inGame: NSpGameReference; inPlayers: NSpPlayerEnumerationPtr); C;
  319. FUNCTION NSpPlayer_GetRoundTripTime(inGame: NSpGameReference; inPlayer: NSpPlayerID): UInt32; C;
  320. FUNCTION NSpPlayer_GetThruput(inGame: NSpGameReference; inPlayer: NSpPlayerID): UInt32; C;
  321.  
  322. {********************  Group Management  *********************}
  323. FUNCTION NSpGroup_New(inGame: NSpGameReference; VAR outGroupID: NSpGroupID): OSStatus; C;
  324. FUNCTION NSpGroup_Dispose(inGame: NSpGameReference; inGroupID: NSpGroupID): OSStatus; C;
  325. FUNCTION NSpGroup_AddPlayer(inGame: NSpGameReference; inGroupID: NSpGroupID; inPlayerID: NSpPlayerID): OSStatus; C;
  326. FUNCTION NSpGroup_RemovePlayer(inGame: NSpGameReference; inGroupID: NSpGroupID; inPlayerID: NSpPlayerID): OSStatus; C;
  327. FUNCTION NSpGroup_GetInfo(inGame: NSpGameReference; inGroupID: NSpGroupID; VAR outInfo: NSpGroupInfoPtr): OSStatus; C;
  328. PROCEDURE NSpGroup_ReleaseInfo(inGame: NSpGameReference; inInfo: NSpGroupInfoPtr); C;
  329. FUNCTION NSpGroup_GetEnumeration(inGame: NSpGameReference; VAR outGroups: NSpGroupEnumerationPtr): OSStatus; C;
  330. PROCEDURE NSpGroup_ReleaseEnumeration(inGame: NSpGameReference; inGroups: NSpGroupEnumerationPtr); C;
  331.  
  332. {*************************  Utilities  **************************}
  333. FUNCTION NSpGetVersion: NumVersion; C;
  334. PROCEDURE NSpClearMessageHeader(VAR inMessage: NSpMessageHeader); C;
  335. FUNCTION NSpGetCurrentTimeStamp(inGame: NSpGameReference): UInt32; C;
  336. FUNCTION NSpConvertOTAddrToAddressReference(VAR inAddress: OTAddress): NSpAddressReference; C;
  337. FUNCTION NSpConvertAddressReferenceToOTAddr(inAddress: NSpAddressReference): OTAddressPtr; C;
  338. PROCEDURE NSpReleaseAddressReference(inAddress: NSpAddressReference); C;
  339.  
  340. {*********************** Advanced/Async routines ***************}
  341.  
  342. TYPE
  343.     NSpCallbackProcPtr = ProcPtr;  { PROCEDURE NSpCallback(inGame: NSpGameReference; inContext: UNIV Ptr; inCode: NSpEventCode; inStatus: OSStatus; inCookie: UNIV Ptr); }
  344.  
  345. FUNCTION NSpInstallCallbackHandler(inHandler: NSpCallbackProcPtr; inContext: UNIV Ptr): OSStatus; C;
  346.  
  347.  
  348. TYPE
  349.     NSpJoinRequestHandlerProcPtr = ProcPtr;  { FUNCTION NSpJoinRequestHandler(inGame: NSpGameReference; VAR inMessage: NSpJoinRequestMessage; inContext: UNIV Ptr; VAR outReason: Str255): BOOLEAN; }
  350.  
  351. FUNCTION NSpInstallJoinRequestHandler(inHandler: NSpJoinRequestHandlerProcPtr; inContext: UNIV Ptr): OSStatus; C;
  352.  
  353.  
  354. TYPE
  355.     NSpMessageHandlerProcPtr = ProcPtr;  { FUNCTION NSpMessageHandler(inGame: NSpGameReference; VAR inMessage: NSpMessageHeader; inContext: UNIV Ptr): BOOLEAN; }
  356.  
  357. FUNCTION NSpInstallAsyncMessageHandler(inHandler: NSpMessageHandlerProcPtr; inContext: UNIV Ptr): OSStatus; C;
  358.  
  359. {$ALIGN RESET}
  360. {$POP}
  361.  
  362. {$SETC UsingIncludes := NetSprocketIncludes}
  363.  
  364. {$ENDC} {__NETSPROCKET__}
  365.  
  366. {$IFC NOT UsingIncludes}
  367.  END.
  368. {$ENDC}
  369.